Syntax

Function name([(parameterList)]) As type

[local variable declarations]

[statements]

[ Return]

[statements]

[exception handlers]

[ Finally]

Notes

The Function statement is used to define a method that can be used on the right side of an expression just like the built-in functions such as Abs, Len, etc. All executable code must be in a Sub or Function statement. A Function differs from a Sub in that a Function can be used on the right side of an expression and a Sub cannot. A function cannot be defined inside another Sub or function. A function executes each line of code from the top down. Once the last line of code is executed, control returns to the line that called the function.

You call a function by using its name followed by its parameters in parentheses.

All variables used in a function must be declared before they are used in a statement. Variables and parameters used in a function are local. Properties can be accessed from within any Sub or function. Local variables are variables that are created each time the function is run and destroyed when the function finishes. Consequently, they can only be accessed by the statements within the function. They are created by using the Dim statement from within a Sub or function. A Dim statement can be placed anywhere within the function.

The Return statement can be used to immediately return control to the statement that called the function and to pass back a value to the left side of the statement. If the Return statement is not called, the null value of the data type returned by the function is returned.

Exception handlers are statements that handle errors. See the RuntimeException class and the Try and Exception blocks for more information.

If your method does not need to return a value, you declare it as a Sub. A Sub is a method that does not return a value. See the Sub statement for more information.

The variable that is returned by a function can be a "regular" single-element variable or an array. When you want to return one value, simply enter the data type of that variable in the Return Type field. To declare the variable as an array, place empty parentheses after the data type. For example, if you want to return an array of integers instead of only one integer, write "Integer()" instead of "Integer" as the function's Return Type field.

If you need to return several values but not in the form of an array, you can use the ByRef keyword when you define the routine's parameters. Using ByRef, you can return the results into the parameters.

A Function method can call itself, resulting in recursion. Too much recursion can lead to stack overflow errors.

Sometimes a function needs to do some cleanup work whether it is finishing normally or aborting early because of an exception. The optional Finally block at the end of the function serves this purpose. Code in this block will be executed even if an exception has occured, whether the exception was handled or not.

Examples

This example is a function that calculates area based on the length and height passed.

This example shows the Area function above written in a simpler form (without the extra local variable).

This example shows the Area function above being called and its returned value assigned to variable.

See Also

Break, Catch, Exit, Finally, Raise, Return, Sub statements; RuntimeException class.